---
title: OIDC Provider
---

# Login via an OIDC provider

You may decide to give your engineering teams access to the dashboard, in order to view and manage their workloads. In this case, you will want to secure access to the dashboard and restrict who can interact with it. Weave GitOps integrates with your OIDC provider and uses standard Kubernetes RBAC to give you fine-grained control of the permissions for the dashboard users.

## Background

OIDC extends the OAuth2 authorization protocol by including an additional field (ID Token) that contains information (claims) about a user's identity. After a user successfully authenticates with the OIDC provider, this information is used by Weave GitOps to impersonate the user in any calls to the Kubernetes API. This allows cluster administrators to use RBAC rules to control access to the cluster and also the dashboard.

## Configuration

In order to login via your OIDC provider, you need to create a Kubernetes secret to store the OIDC configuration. This configuration consists of the following parameters:

| Parameter         |  Description                                                                                                                      | Default   |
| ------------------|  -------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `issuerURL`       |  The URL of the issuer, typically the discovery URL without a path                                                                |           |
| `clientID`        |  The client ID that has been setup for Weave GitOps in the issuer                                                                 |           |
| `clientSecret`    |  The client secret that has been setup for Weave GitOps in the issuer                                                             |           |
| `redirectURL`     |  The redirect URL that has been setup for Weave GitOps in the issuer, typically the dashboard URL followed by `/oauth2/callback ` |           |
| `tokenDuration`   |  The time duration that the ID Token will remain valid, after successful authentication                                           | "1h0m0s"  |

Ensure that your OIDC provider has been setup with a client ID/secret and the redirect URL of the dashboard.

Create a secret named `oidc-auth` in the `flux-system` namespace with these parameters set:

```sh
kubectl create secret generic oidc-auth \
  --namespace flux-system \
  --from-literal=issuerURL=<oidc-issuer-url> \
  --from-literal=clientID=<client-id> \
  --from-literal=clientSecret=<client-secret> \
  --from-literal=redirectURL=<redirect-url> \
  --from-literal=tokenDuration=<token-duration>
```

Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identity will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly but it is recommended to read the [service account](service-account-permissions.mdx) and [user](user-permissions.mdx) permissions pages to understand which actions are needed for Weave GitOps to function correctly.

## Customizing

For some OIDC configurations, you may need to customise the requested [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) or [claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims).

### Scopes

By default, the following scopes are requested "openid","offline_access","email","groups".

The "openid" scope is **mandatory** for OpenID auth, and the "email", and "groups" scopes are commonly used as unique identifiers in organisations.

We use "offline_access" to allow us to refresh OIDC tokens to keep login sessions alive for as long as a refresh token is valid.

You can however change the defaults.
```sh
kubectl create secret generic oidc-auth \
  --namespace flux-system \
  --from-literal=issuerURL=<oidc-issuer-url> \
  --from-literal=clientID=<client-id> \
  --from-literal=clientSecret=<client-secret> \
  --from-literal=redirectURL=<redirect-url> \
  --from-literal=tokenDuration=<token-duration> \
  --from-literal=customScopes=custom,scopes
```
The format for the `customScopes` key is a comma-separated list of scopes to request, in this case, "custom" and "scopes" would be requested, in addition to "openid".

### Claims

By default, the following claims are parsed from the OpenID [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#CodeIDToken) "email" and "groups", these are presented as the `user` and `groups` when we communicate with your Kubernetes API server.

This is equivalent to [configuring](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server) your `kube-apiserver` with `--oidc-username-claim=email --oidc-groups-claim=groups`.

Again, you can configure these from the `oidc-auth` `Secret`.

```sh
kubectl create secret generic oidc-auth \
  --namespace flux-system \
  --from-literal=issuerURL=<oidc-issuer-url> \
  --from-literal=clientID=<client-id> \
  --from-literal=clientSecret=<client-secret> \
  --from-literal=redirectURL=<redirect-url> \
  --from-literal=tokenDuration=<token-duration> \
  --from-literal=claimUsername=sub \
  --from-literal=claimGroups=groups
```
There are two separate configuration keys, you can override them separately, these should match your `kube-apiserver` configuration.

### Login UI

The label of the OIDC button on the login screen is configurable via a feature flag environment variable.
This can give your users a more familiar experience when logging in.

Adjust the configuration in the helm `values.yaml` file or the `spec.values` section of the Weave Gitops `HelmRelease` resource:

#### Weave Gitops

```yaml
envVars:
  - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL
    value: "Login with ACME"
```

#### Weave Gitops Enterprise

```yaml
extraEnvVars:
  - name: WEAVE_GITOPS_FEATURE_OIDC_BUTTON_LABEL
    value: "Login with ACME"
```